Bootloaders & Hardware Boot Manual

This document provides a comprehensive technical manual detailing the bootloader generation, partitioning schemes, firmware integration, and kernel boot chains across all 12 supported architecture targets in Void-Builder.

1. Boot Architecture Overview Matrix

Architecture Target	Primary Bootloader	Partitioning Scheme	Firmware / Boot Files	Kernel Image Name
`x86_64`	Hybrid SYSLINUX (BIOS) + GRUB2 (UEFI)	ISO 9660 / El Torito	`isolinux.bin`, `isohdpfx.bin`, `efiboot.img`	`vmlinuz`
`x86_64-musl`	Hybrid SYSLINUX (BIOS) + GRUB2 (UEFI)	ISO 9660 / El Torito	`isolinux.bin`, `isohdpfx.bin`, `efiboot.img`	`vmlinuz`
`i686`	Hybrid SYSLINUX (BIOS) + GRUB2 (UEFI)	ISO 9660 / El Torito	`isolinux.bin`, `isohdpfx.bin`, `efiboot.img`	`vmlinuz`
`aarch64`	GRUB2 ARM64 EFI	ISO 9660 / UEFI FAT	`bootaa64.efi`, `efiboot.img`	`vmlinux`
`aarch64-musl`	GRUB2 ARM64 EFI	ISO 9660 / UEFI FAT	`bootaa64.efi`, `efiboot.img`	`vmlinux`
`armv7l`	GRUB ARM EFI / U-Boot	ISO 9660 / FAT	`bootarm.efi`, `efiboot.img`	`vmlinux`
`armv7l-musl`	GRUB ARM EFI / U-Boot	ISO 9660 / FAT	`bootarm.efi`, `efiboot.img`	`vmlinux`
`rpi-aarch64`	Raspberry Pi Native Firmware	MBR (VFAT + EXT4)	`bootcode.bin`, `start.elf`, `cmdline.txt`	`kernel8.img`
`rpi-armv7l`	Raspberry Pi Native Firmware	MBR (VFAT + EXT4)	`bootcode.bin`, `start.elf`, `cmdline.txt`	`kernel7.img`
`rpi-armv6l`	Raspberry Pi Native Firmware	MBR (VFAT + EXT4)	`bootcode.bin`, `start.elf`, `cmdline.txt`	`kernel.img`
`pinebookpro`	Rockchip RK3399 U-Boot	GPT (VFAT + EXT4)	`idbloader.img`, `u-boot.itb`	`vmlinuz`
`asahi`	GRUB2 ARM64 EFI	MBR/GPT (VFAT + EXT4)	`bootaa64.efi`, `m1n1` stage	`vmlinuz-asahi`

2. PC Hybrid ISO Boot Mechanism (x86_64 / i686)

PC live ISO images generated by VoidEngine support dual boot capability: booting under legacy BIOS systems and 32/64-bit UEFI systems.

A. BIOS Legacy Boot (SYSLINUX)

Files Location: boot/isolinux/ inside the ISO image.
Boot Entry Binary: isolinux.bin
MBR Sector Embedding: VoidEngine extracts isohdpfx.bin from usr/lib/syslinux/isohdpfx.bin and passes it to xorriso via -isohybrid-mbr. This enables booting when the ISO is written directly to a USB drive with dd.
Menu System: Uses vesamenu.c32 to render a 800x600 graphical menu using the background splash PNG (configs/assets/data/splash.png).

Generated `isolinux.cfg` Template:

DEFAULT vesamenu.c32
PROMPT 0
TIMEOUT 100

MENU TITLE Pepvoid Live ISO
MENU BACKGROUND /boot/isolinux/splash.png

LABEL void_live
  MENU LABEL Boot Void Linux Live (x86_64)
  LINUX /boot/vmlinuz
  INITRD /boot/initrd
  APPEND quiet splash live.user=live live.autologin rd.live.overlay.overlayfs=1

B. UEFI Boot (GRUB2 EFI)

Boot Image: boot/grub/efiboot.img (FAT16 image embedded inside ISO).
EFI Binary: EFI/BOOT/BOOTX64.EFI (64-bit) or EFI/BOOT/BOOTIA32.EFI (32-bit).

xorriso Integration: Linked into the ISO header via:

-eltorito-alt-boot \
-e boot/grub/efiboot.img \
-no-emul-boot \
-isohybrid-gpt-basdat \
-isohybrid-apm-hfsplus

C. PC virtual disk images (VDI, QCOW2, VMDK, IMG/RAW)

These images use UEFI GRUB on a FAT ESP and keep the kernel/initramfs on the root partition labelled void_root. The standalone EFI loader must load part_gpt (and part_msdos for MBR targets) before searching for that partition. Merely including the module files in the standalone memdisk does not ensure partition drivers are loaded. Without them, GRUB can list (hd0) but no partitions, then report no such device: void_root followed by file /boot/vmlinuz not found even when the kernel is present.

The disk builder explicitly loads the partition/filesystem modules, selects a matching nonempty kernel/initramfs pair, and uses their filenames in both the embedded configuration and /boot/grub/grub.cfg. It also creates /boot/efi before exporting the root filesystem so the ESP mount in /etc/fstab succeeds. Missing boot files abort the build before packaging.

The disk menu defaults to the newest complete kernel/initramfs pair and remains visible for five seconds. It offers normal boot, safe graphics (nomodeset), and an Advanced options for Void Linux submenu containing normal and recovery entries for each complete installed kernel. Recovery uses Void/runit’s single mode. Incomplete kernel/initramfs pairs are omitted. UEFI firmware settings appear only when supported by the firmware; restart and shutdown entries are also available. These entries apply to disk images; the live ISO menu is generated separately.

3. Raspberry Pi Single-Board Computers (`rpi-*`)

Raspberry Pi computers do not use traditional BIOS or UEFI. Instead, the VideoCore GPU boots first, reads files from the primary VFAT partition, and loads the ARM Linux kernel.

Disk Partition Map (MBR)

Sector 2048 to +256MiB: Partition 1 (Type 0x0c FAT16, bootable). Mounted as /boot.
Sector +256MiB to End: Partition 2 (Type 0x83 Linux EXT4). Mounted as /.

Critical `/boot` Firmware Files

bootcode.bin: GPU bootloader stage.
start.elf: VideoCore GPU firmware binary.
fixup.dat: GPU memory allocation configuration file.
config.txt: Raspberry Pi hardware configuration options.
cmdline.txt: One-line kernel parameters.

Generated `cmdline.txt` Format:

root=PARTUUID=a1b2c3d4-02 rw rootwait console=ttyAMA0,115200 console=tty1 quiet splash

4. Pinebook Pro Laptop (`pinebookpro`)

The Pinebook Pro is powered by the Rockchip RK3399 ARM64 SoC. It boots using U-Boot written to raw disk sectors before the first partition.

GPT Sector Map

Sectors 0 to 63: GPT Header & Partition Table.
Sector 64 (32 KiB Offset): idbloader.img written via dd if=idbloader.img of=/dev/sdX bs=512 seek=64 conv=notrunc,fsync.
Sector 16384 (8 MiB Offset): u-boot.itb written via dd if=u-boot.itb of=/dev/sdX bs=512 seek=16384 conv=notrunc,fsync.
Partition 1 (512MiB, FAT16): /boot partition containing Linux kernel and initramfs.
Partition 2 (Remainder, EXT4): Root filesystem.

5. Apple Silicon Macs (`asahi`)

Apple Silicon Macs (M1/M2/M3 chips) boot via Apple’s proprietary boot chain (m1n1 stage 1 -> U-Boot stage 2 -> GRUB2 EFI stage 3).

Asahi Boot Sequence

PlatformEngine detects asahi target architecture.
Partition 1 (256MiB FAT16) is formatted for EFI.

GRUB ARM64 EFI is installed inside chroot:

grub-install --target=arm64-efi --efi-directory=/boot --removable /dev/loopX

Executes xbps-reconfigure -f linux-asahi to generate Apple Silicon device trees (.dtb files) and kernel modules.